<?php
/**
* Template interface. All template classes implement this interface.
*
* Copyright (c) 2009 James Gauld <james@jamesgauld.net>
* This file is part of Scribble.
* @license http://www.scribblecms.co.uk/license.txt
*
* @package Scribble
*/
interface IScribbleTemplate {

	/**
	* Gather data from the given array (usually $_POST) and returns an object
	* that can be passed to PageVersionModel::setInnerContent() or
	* PageVersionModel::setOuterContent() (depending on this template's type).
	*
	* The PageVersion model is also passed giving you the chance to manipulate it
	* directly if needs be (for example, to create bindings or relationships with
	* other models.)
	*
	* @param PageVersionModel The Page version into which the data will be stored
	* @param array Content of $_POST
	* @return mixed
	*/
	public function gatherPopulatorData(PageVersionModel $version, $data=array());

	/**
	* Returns the template category under which this template should be listed.
	*
	* @return string
	*/
	public function getCategory();

	/**
	* Return the View that gets rendered in the front-end of the website.
	*
	* Rather than call this method directly, it is recommended to go through
	* $pageVersion->getInner/OuterView() which will manipulate the resulting View
	* to provide a few useful properties.
	*
	* This MUST return an instance of the ScribblePublicView class.
	*
	* @param PageVersionModel Model whose content will be rendered
	* @param string Revision ID
	* @return ScribblePublicView
	*/
	public function getFrontEndView(PageVersionModel $version);

	/**
	* Return a long description of this template; the features it offers and the
	* design elements it uses.
	*
	* @return string
	*/
	public function getLongDescription();

	/**
	* Return the view that contains an HTML form for gathering content input from
	* the author, ie. appears in the administrative UI.
	*
	* If your template doesn't need a populator form, return a View with it's
	* source set to NULL.
	*
	* Bear in mind that this View will be rendered in the page-editing UI along
	* with other form elements, so to avoid field name conflicts the recommended
	* convention is to use "inner[...]" or "outer[...]" name wrappers (depending
	* on this template's type - inner/outer) so your field will appear in 
	* $_POST['inner'][...] or $_POST['outer'][...]
	*
	* This must return an instance of the ScribbleAdminView class.
	*
	* @param PageVersionModel Model whose content will pre-populate form
	* @param string Revision ID
	* @return ScribbleAdminView
	*/
	public function getPopulatorView(PageVersionModel $content);

	/**
	* Return a short description of this template to aid content authors in
	* choosing the appropriate template for a Page.
	*
	* @return string
	*/
	public function getShortDescription();

	/**
	* Return the title of this template (a human friendly name for this template.)
	*
	* @return string
	*/
	public function getTitle();

	/**
	* Return this template's type, one of the following values:
	* ScribbleTemplate::TYPE_INNER
	* ScribbleTemplate::TYPE_OUTER
	*
	* @return int
	*/
	public function getType();

	/**
	* This method is called just after a failed or successful save of a Page model
	* in the page-editor UI.
	*
	* It can be used, for example, to clean up objects or save additional data
	* after a failed or successful save.
	*
	* @param PageModel The page that was (or was not successfully) saved
	* @param bool The success flag
	* @return void
	*/
	public function saveHandler(PageModel $page, $isSuccess);

	/**
	* Validates the content in the given $page and returns the result. Any
	* informational/error messages are added to the $messages array.
	*
	* Depending on this template's type, the "innercontent" or "outercontent"
	* field of $page will need to be validated here.
	*
	* @param PageVersionModel Page version whose content will be validated
	* @param array Any error messages will be added to this array
	* @return bool
	*/
	public function validatePageContent(PageVersionModel $page, &$messages);
}
?>